home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Sound / mpega_library / developer / mpega.doc
Text File  |  1998-06-22  |  9KB  |  255 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpega/MPEGA_close
  4. mpega/MPEGA_decode_frame
  5. mpega/MPEGA_find_sync
  6. mpega/MPEGA_open
  7. mpega/MPEGA_scale
  8. mpega/MPEGA_seek
  9. mpega/MPEGA_time
  10. mpega/MPEGA_close                                           mpega/MPEGA_close
  11.  
  12.    NAME
  13.         MPEGA_close -- close an MPEG Audio stream.
  14.  
  15.    SYNOPSIS
  16.         MPEGA_close( mpega_stream );
  17.                           a0
  18.  
  19.         void MPEGA_close( MPEGA_STREAM * );
  20.  
  21.    FUNCTION
  22.         Closes an MPEG Audio stream. Once this call has been made, the
  23.         stream can no longer be accessed.
  24.  
  25.    INPUTS
  26.         mpega_stream - the MPEG Audio stream to close.
  27.  
  28.    RESULT
  29.  
  30.    SEE ALSO
  31.         MPEGA_open()
  32.  
  33.    BUGS
  34.  
  35. mpega/MPEGA_decode_frame                             mpega/MPEGA_decode_frame
  36.  
  37.    NAME
  38.         MPEGA_decode_frame -- Decode one frame of MPEG Audio stream.
  39.  
  40.    SYNOPSIS
  41.         sample_count = MPEGA_decode_frame( mpega_stream, pcm );
  42.              d0                                 a0       a1
  43.  
  44.         LONG MPEGA_decode_frame( MPEGA_STREAM *, WORD *pcm[ MPEGA_MAX_CHANNELS ] );
  45.  
  46.    FUNCTION
  47.         This function decodes one frame of MPEG Audio stream. Decoded audio
  48.         samples are stored in given pcm buffers (16-bit samples). The function
  49.         returns the number of decoded samples (for one channel) or an error code
  50.         (negative number). The maximum number of decoded samples will not exceed
  51.         MPEGA_PCM_SIZE. The number of samples depend on the MPEG Audio stream
  52.         type (norm and layer) and on the decoded frequency output division.
  53.         The channel 0 is Left or Mono, channel 1 is Right.
  54.  
  55.    INPUTS
  56.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  57.         pcm - Array of MPEGA_MAX_CHANNELS buffers of MPEGA_PCM_SIZE WORD's.
  58.  
  59.    RESULT
  60.         pcm - These arrays will be filled with audio pcm samples if sample_count > 0.
  61.         sample_count - number of samples decoded for each channel. This number
  62.             may be 0 if current frame was skipped because decoder is not yet
  63.             synchronized, this is * NOT * a decoding error.
  64.             If this number is < 0, end of stream is reached (= MPEGA_ERR_EOF)
  65.             or an error was found (MPEGA_ERR_BADFRAME).
  66.  
  67.    SEE ALSO
  68.         MPEGA_open(), MPEGA_close()
  69.  
  70.    BUGS
  71.  
  72. mpega/MPEGA_find_sync                                   mpega/MPEGA_find_sync
  73.  
  74.    NAME
  75.         MPEGA_find_sync -- Find an MPEG Audio sync word in a buffer.
  76.  
  77.    SYNOPSIS
  78.         sync_pos = MPEGA_find_sync( buffer, buffer_size );
  79.            d0                         a0         d0
  80.  
  81.         LONG MPEGA_find_sync( BYTE *, LONG );
  82.  
  83.    FUNCTION
  84.         This function searches for an MPEG Audio sync word in a buffer.
  85.         You can use this function to see if a file contains MPEG Audio data.
  86.         If the function returns >= 0 value, a valid MPEG Audio header was found.
  87.  
  88.    INPUTS
  89.         buffer - BYTE buffer to watch
  90.         buffer_size - Number of bytes of given buffer
  91.  
  92.    RESULT
  93.         sync_pos - sync postion of a valid MPEG Audio frame or MPEGA_ERR_NO_SYNC
  94.             if no valid frame found.
  95.  
  96.    SEE ALSO
  97.  
  98.    BUGS
  99.  
  100. mpega/MPEGA_open                                             mpega/MPEGA_open
  101.  
  102.    NAME
  103.         MPEGA_open -- Open an MPEG Audio stream.
  104.  
  105.    SYNOPSIS
  106.         mpega_stream = MPEGA_open( stream_name, ctrl );
  107.              d0                         A0       a1
  108.  
  109.         MPEGA_STREAM *MPEGA_open( char *, MPEGA_CTRL * );
  110.  
  111.    FUNCTION
  112.         Opens an MPEG Audio stream and returns an mpeg audio stream structure.
  113.         The stream name is the MPEG Audio filename if standard file access is used.
  114.         The ctrl structure controls the stream access and the decoding
  115.         parameters. If you want a standard file access to the streams, set the
  116.         bs_access field of MPEGA_CTRL to NULL. Otherwise, set it to a pointer
  117.         to a Hook that specifies your custom access to the stream. It this case,
  118.         your Hook function will be called in this way:
  119.  
  120.          ULONG __saveds __asm HookFunc( register __a0 struct Hook  *hook,
  121.                                         register __a2 APTR          handle,
  122.                                         register __a1 MPEGA_ACCESS *access );
  123.  
  124.          MPEGA_ACCESS struct specifies bitstream access function & parameters
  125.  
  126.          access->func == MPEGA_BSFUNC_OPEN
  127.             open the bitstream
  128.             access->data.open.buffer_size is the i/o block size your read function can use
  129.             access->data.open.stream_size is the total size of the current stream
  130.                                           (in bytes, set it to 0 if unknown)
  131.             return your file handle (or NULL if failed)
  132.          access->func == MPEGA_BSFUNC_CLOSE
  133.             close the bitstream
  134.             return 0 if ok
  135.          access->func == MPEGA_BSFUNC_READ
  136.             read bytes from bitstream.
  137.             access->data.read.buffer is the destination buffer.
  138.             access->data.read.num_bytes is the number of bytes requested for read.
  139.             return # of bytes read or 0 if EOF.
  140.          access->func == MPEGA_BSFUNC_SEEK
  141.             seek into the bitstream
  142.             access->data.seek.abs_byte_seek_pos is the absolute byte position to reach.
  143.             return 0 if ok
  144.  
  145.         Control structure contains Layers decoding settings, one for Layers I & II and
  146.         one for Layer III (which is more CPU intensive). These settings controls the
  147.         audio quality, the output frequency division and the stereo to mono conversion.
  148.         Control structure allows also to choose the stream buffer size, which set the
  149.         amount of bytes read for stream in a block.
  150.         For more details about this structure see <libraries/mpega.h> .
  151.  
  152.         If the returned value is NULL, the stream can't be opened (if it's not an
  153.         MPEG Audio stream for example). Otherwise, mpega_stream (read only) contains
  154.         informations about current stream and actual decoding values.
  155.  
  156.         * WARNING * Only the task that called MPEGA_open can safely call the other functions
  157.         that use the mpega_stream.
  158.  
  159.    INPUTS
  160.         stream_name - Name of the stream to open.
  161.         ctrl - Decoding control.
  162.  
  163.    RESULTS
  164.         mpega_stream - The stream structure, use it to get information about
  165.             current stream. You should pass this to other functions.
  166.  
  167.    SEE ALSO
  168.         MPEGA_close(), MPEGA_decode_frame()
  169.  
  170.    BUGS
  171.  
  172. mpega/MPEGA_scale                                           mpega/MPEGA_scale
  173.  
  174.    NAME
  175.         MPEGA_scale -- Set the output scale for the current stream (V2)
  176.  
  177.    SYNOPSIS
  178.         error = MPEGA_scale( mpega_stream, scale_percent );
  179.           d0                      a0            d0
  180.  
  181.         LONG MPEGA_scale( MPEGA_STREAM *, LONG );
  182.  
  183.    FUNCTION
  184.         This function set the output scale of the decoded samples.
  185.         It is possible to increase or to decrease the output samples dynamic.
  186.         A scale_percent of 200 will double the output sample values and
  187.         a scale_percent of 50 will halve the values.
  188.  
  189.    INPUT
  190.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  191.         scale_percent - The scaling factor in %
  192.  
  193.    RESULT
  194.         error - 0 if Ok or < 0 if error (see MPEGA_ERR_xxx)
  195.  
  196.    SEE ALSO
  197.  
  198.    BUGS
  199.  
  200. mpega/MPEGA_seek                                             mpega/MPEGA_seek
  201.  
  202.    NAME
  203.         MPEGA_seek -- Seek into an MPEG Audio stream.
  204.  
  205.    SYNOPSIS
  206.         error = MPEGA_seek( mpega_stream, ms_time_position );
  207.           d0                     a0              d0
  208.  
  209.         LONG MPEGA_seek( MPEGA_STREAM *, ULONG );
  210.  
  211.    FUNCTION
  212.         This function allows to seek into an opened stream. The seek
  213.         position is a time position in milliseconds. If the seek failed,
  214.         the function returns an error (MPEGA_ERR_EOF if outside of stream).
  215.  
  216.    INPUTS
  217.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  218.         ms_time_position - Time position of seek.
  219.  
  220.    RESULT
  221.         error - 0 if Ok or < 0 if error (see MPEGA_ERR_xxx)
  222.  
  223.    SEE ALSO
  224.         MPEGA_time()
  225.  
  226.    BUGS
  227.  
  228. mpega/MPEGA_time                                             mpega/MPEGA_time
  229.  
  230.    NAME
  231.         MPEGA_time -- Get the current time position of an MPEG Audio stream
  232.  
  233.    SYNOPSIS
  234.         error = MPEGA_time( mpega_stream, ms_time_position );
  235.           d0                     a0             a1
  236.  
  237.         LONG MPEGA_time( MPEGA_STREAM *, ULONG * );
  238.  
  239.    FUNCTION
  240.         This function gets the current time position of an opened stream.
  241.         The return time position is given in milliseconds.
  242.  
  243.    INPUTS
  244.         mpega_stream - Opened MPEG Audio stream obtain from MPEGA_open()
  245.  
  246.    RESULT
  247.         ms_time_position - Current time position.
  248.         error - 0 if Ok or < 0 if error (see MPEGA_ERR_xxx)
  249.  
  250.    SEE ALSO
  251.         MPEGA_seek()
  252.  
  253.    BUGS
  254.  
  255.